[Beta] Retrieve objects

curl --request POST \
  --url https://api.topsort.com/toptimize/v1/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slots": 5,
  "opaqueUserId": "u_9ske45",
  "seedProductIds": [
    "p_PJbnN",
    "p_ojng4"
  ],
  "mode": "all",
  "objectType": "listings",
  "deviceType": "mobile"
}
'

import requests

url = "https://api.topsort.com/toptimize/v1/retrieval"

payload = {
    "slots": 5,
    "opaqueUserId": "u_9ske45",
    "seedProductIds": ["p_PJbnN", "p_ojng4"],
    "mode": "all",
    "objectType": "listings",
    "deviceType": "mobile"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slots: 5,
    opaqueUserId: 'u_9ske45',
    seedProductIds: ['p_PJbnN', 'p_ojng4'],
    mode: 'all',
    objectType: 'listings',
    deviceType: 'mobile'
  })
};

fetch('https://api.topsort.com/toptimize/v1/retrieval', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/toptimize/v1/retrieval",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slots' => 5,
    'opaqueUserId' => 'u_9ske45',
    'seedProductIds' => [
        'p_PJbnN',
        'p_ojng4'
    ],
    'mode' => 'all',
    'objectType' => 'listings',
    'deviceType' => 'mobile'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/toptimize/v1/retrieval"

	payload := strings.NewReader("{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/toptimize/v1/retrieval")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/toptimize/v1/retrieval")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}"

response = http.request(request)
puts response.read_body

{
  "objectType": "listings",
  "objects": [
    {
      "id": "p_xh90s",
      "score": 0.978
    },
    {
      "id": "p_12lp0",
      "score": 0.953
    },
    {
      "id": "p_ds7ui",
      "score": 0.877
    }
  ]
}

{
  "errCode": "bad_request",
  "docUrl": "https://api.docs.topsort.com/reference/errors",
  "message": "could not find the provided resolved bid id"
}

Toptimize

[Beta] Retrieve objects

⚠️ Beta Access Required

Contact your sales representative to gain access to this endpoint and start using it.

Use the /retrieval endpoint to get recommendations of which products are relevant given a certain context. Context is provided by user information, plus seed products. This can be used to retrieve object to display on a PDP (single seed product) or in a cart (multiple seed products).

In order to provide retrieval, Topsort requires that events are also sent, as a source of information.

POST

toptimize

retrieval

[Beta] Retrieve objects

curl --request POST \
  --url https://api.topsort.com/toptimize/v1/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slots": 5,
  "opaqueUserId": "u_9ske45",
  "seedProductIds": [
    "p_PJbnN",
    "p_ojng4"
  ],
  "mode": "all",
  "objectType": "listings",
  "deviceType": "mobile"
}
'

import requests

url = "https://api.topsort.com/toptimize/v1/retrieval"

payload = {
    "slots": 5,
    "opaqueUserId": "u_9ske45",
    "seedProductIds": ["p_PJbnN", "p_ojng4"],
    "mode": "all",
    "objectType": "listings",
    "deviceType": "mobile"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    slots: 5,
    opaqueUserId: 'u_9ske45',
    seedProductIds: ['p_PJbnN', 'p_ojng4'],
    mode: 'all',
    objectType: 'listings',
    deviceType: 'mobile'
  })
};

fetch('https://api.topsort.com/toptimize/v1/retrieval', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/toptimize/v1/retrieval",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'slots' => 5,
    'opaqueUserId' => 'u_9ske45',
    'seedProductIds' => [
        'p_PJbnN',
        'p_ojng4'
    ],
    'mode' => 'all',
    'objectType' => 'listings',
    'deviceType' => 'mobile'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/toptimize/v1/retrieval"

	payload := strings.NewReader("{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/toptimize/v1/retrieval")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/toptimize/v1/retrieval")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slots\": 5,\n  \"opaqueUserId\": \"u_9ske45\",\n  \"seedProductIds\": [\n    \"p_PJbnN\",\n    \"p_ojng4\"\n  ],\n  \"mode\": \"all\",\n  \"objectType\": \"listings\",\n  \"deviceType\": \"mobile\"\n}"

response = http.request(request)
puts response.read_body

{
  "objectType": "listings",
  "objects": [
    {
      "id": "p_xh90s",
      "score": 0.978
    },
    {
      "id": "p_12lp0",
      "score": 0.953
    },
    {
      "id": "p_ds7ui",
      "score": 0.877
    }
  ]
}

{
  "errCode": "bad_request",
  "docUrl": "https://api.docs.topsort.com/reference/errors",
  "message": "could not find the provided resolved bid id"
}

Authorizations

Authorization

string

header

required

A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API.

Body

application/json

The context information for the predictions, including which metrics to predict.

Request to retrieve objects based on context.

slots

integer

required

How many objects to retrieve.

Required range: 1 <= x <= 100

Examples:

10

50

opaqueUserId

string

required

The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests.

Example:

"71303ce0-de89-496d-8270-6434589615e8"

objectType

enum<string>

required

The type of object that needs to be retrieved.

Available options:

listings,

banners

seedProductIds

string[]

required

page

Page · object

Information about the page where an auction or event occurs.

Show child attributes

deviceType

enum<string>

The device the user is on.

Available options:

desktop,

mobile

Example:

"mobile"

mode

enum<string>

default:all

Retrieval mode, how to interpret the context to get objects.

Available options:

all,

complement,

similar

Response

The retrieval results. Each retrieved products is accompanied by their relevancy score.

The result of a retrieval request, containing relevant objects with scores.

objectType

enum<string>

required

The type of object that was predicted.

Available options:

listings,

banners

objects

object[]

required

Retrieved objects.

Show child attributes

General

Auction examples

Webhook examples

Auctions

Events

Toptimize

Toppie API

Campaign API

Catalog API

Billing API

Reporting API

Invitation API

User API

Webhooks API

Assets API

Segments Service

Offsite Ads API

Forecasting Service

Media API

Placement API

Export API

API Reference

[Beta] Retrieve objects

Authorizations

Body

Response